package com.kexio.auth.metrics;

/**
 * 统一安全指标接口
 * 
 * 合并了原有的3套指标接口：
 * - AuthorizationMetrics（权限评估指标）
 * - SecurityMetrics（安全相关指标）
 * - SecurityOpsMetrics（安全运维指标）
 * 
 * 设计原则：
 * - 减少接口碎片化
 * - 统一指标命名规范
 * - 简化实现复杂度
 * - 便于监控系统集成
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface UnifiedSecurityMetrics {
    
    // ==================== 认证指标 ====================
    
    /**
     * 记录登录成功
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     */
    void onLoginSuccess(String tenantId, String userId);
    
    /**
     * 记录登录失败
     * 
     * @param tenantId 租户ID
     * @param username 用户名
     * @param reason 失败原因
     */
    void onLoginFailure(String tenantId, String username, String reason);
    
    /**
     * 记录令牌刷新成功
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     */
    void onRefreshSuccess(String tenantId, String userId);
    
    /**
     * 记录令牌刷新失败
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @param reason 失败原因
     */
    void onRefreshFailure(String tenantId, String userId, String reason);
    
    /**
     * 记录用户登出
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @param success 是否成功
     */
    void onLogout(String tenantId, String userId, boolean success);
    
    // ==================== 权限评估指标 ====================
    
    /**
     * 记录权限表达式评估
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @param expression 表达式内容
     * @param success 是否成功
     * @param elapsedMs 耗时毫秒
     */
    void onExpressionEvaluated(String tenantId, String userId, String expression, boolean success, long elapsedMs);
    
    /**
     * 记录权限表达式错误
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @param expression 表达式
     * @param error 错误信息
     */
    void onExpressionError(String tenantId, String userId, String expression, String error);
    
    // ==================== 会话指标 ====================
    
    /**
     * 记录会话创建
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @param success 是否成功
     * @param elapsedMs 耗时毫秒
     */
    void onSessionCreate(String tenantId, String userId, boolean success, long elapsedMs);
    
    /**
     * 记录会话更新
     * 
     * @param sessionId 会话ID
     * @param success 是否成功
     * @param elapsedMs 耗时毫秒
     */
    void onSessionUpdate(String sessionId, boolean success, long elapsedMs);
    
    /**
     * 记录会话终止
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @param success 是否成功
     * @param elapsedMs 耗时毫秒
     */
    void onSessionTerminate(String tenantId, String userId, String sessionId, boolean success, long elapsedMs);
    
    /**
     * 记录批量会话终止
     * 
     * @param tenantId 租户ID
     * @param userId 用户ID
     * @param terminatedCount 终止的会话数量
     * @param elapsedMs 耗时毫秒
     */
    void onSessionTerminateAll(String tenantId, String userId, int terminatedCount, long elapsedMs);
    
    // ==================== JWT撤销指标 ====================
    
    /**
     * 记录JWT撤销操作
     * 
     * @param tenantId 租户ID
     * @param scope 撤销范围（token, user, tenant等）
     * @param count 撤销数量
     * @param success 是否成功
     * @param elapsedMs 耗时毫秒
     */
    void onJwtRevoke(String tenantId, String scope, int count, boolean success, long elapsedMs);
    
    /**
     * 记录JWT黑名单检查
     * 
     * @param tenantId 租户ID
     * @param scope 检查范围
     * @param success 是否成功
     * @param elapsedMs 耗时毫秒
     */
    void onJwtBlacklistCheck(String tenantId, String scope, boolean success, long elapsedMs);
    
    /**
     * 记录JWT黑名单清理
     * 
     * @param tenantId 租户ID
     * @param scannedCount 扫描数量
     * @param elapsedMs 耗时毫秒
     */
    void onJwtBlacklistCleanup(String tenantId, int scannedCount, long elapsedMs);
    
    // ==================== 缓存指标 ====================
    
    /**
     * 记录缓存命中
     * 
     * @param cacheType 缓存类型（user, session, jwt等）
     * @param tenantId 租户ID
     * @param hit 是否命中
     * @param elapsedMs 耗时毫秒
     */
    void onCacheAccess(String cacheType, String tenantId, boolean hit, long elapsedMs);
    
    /**
     * 记录缓存失效
     * 
     * @param cacheType 缓存类型
     * @param tenantId 租户ID
     * @param evictedCount 失效数量
     * @param elapsedMs 耗时毫秒
     */
    void onCacheEviction(String cacheType, String tenantId, int evictedCount, long elapsedMs);
    
    // ==================== 安全事件指标 ====================
    
    /**
     * 记录安全事件
     * 
     * @param eventType 事件类型（suspicious_login, brute_force等）
     * @param tenantId 租户ID
     * @param userId 用户ID（可选）
     * @param severity 严重程度（INFO, WARN, ERROR）
     * @param details 事件详情
     */
    void onSecurityEvent(String eventType, String tenantId, String userId, String severity, String details);
    
    /**
     * 记录性能警告
     * 
     * @param operation 操作类型
     * @param tenantId 租户ID
     * @param elapsedMs 耗时毫秒
     * @param threshold 阈值毫秒
     */
    void onPerformanceWarning(String operation, String tenantId, long elapsedMs, long threshold);
}
